<!DOCTYPE HTML>
<html>
<head>
<title>ComObjActive() | AutoHotkey</title>
<meta name="description" content="The ComObjActive function retrieves a running object that has been registered with OLE." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>ComObjActive() <span class="ver">[AHK_L 53+]</span></h1>

<p>检索已使用 OLE(对象连接与嵌入) 注册的运行对象.</p>
<pre class="Syntax">ComObject := <span class="func">ComObjActive</span>(CLSID)</pre>

<p id="param">创建一个表示要作为参数或返回值传递的类型化值的对象.</p>
<pre class="Syntax">ParamObj := <span class="func">ComObject</span>(VarType, Value <span class="optional">, Flags</span>)</pre>
<hr>
<p class="warning"><strong>不建议:</strong> 不推荐使用以下方法, 后续版本中可能被替换或不再支持.</p>
<p id="missing">在调用 COM(组件对象模型) 对象的方法时创建一个可用于替代可选参数默认值的对象. <span class="ver">[v1.1.12+]</span>: 这种函数已废弃使用. 作为代替, 使用两个连续的逗号, 如 <code>Obj.Method(1,,3)</code></p>
<pre class="Syntax">ParamObj := <span class="func">ComObjMissing</span>()</pre>

<p id="enwrap">装包或拆包位于可用对象的原始 <a href="http://msdn.microsoft.com/en-us/library/dd318520.aspx">IDispatch</a> 指针, 并自动调用 AddRef(增加引用).</p>
<pre class="Syntax">
ComObject := <span class="func">ComObjEnwrap</span>(DispPtr)
DispPtr := <span class="func">ComObjUnwrap</span>(ComObject)
</pre>
<p>要写更多面向未来的代码, 请改用以下代码:</p>
<pre>ComObject := ComObject(9, DispPtr, 1), ObjAddRef(DispPtr)
DispPtr := <a href="ComObjValue.htm">ComObjValue</a>(ComObject), ObjAddRef(DispPtr)</pre>
<hr>

<h2>参数</h2>
<dl>

  <dt>CLSID</dt>
  <dd><p>要检索的 COM 对象的 CLSID 或可读 Prog ID.</p></dd>

  <dt>ComObject</dt>
  <dd><p>可以使用<a href="../Objects.htm#Usage_Objects">对象语法</a>的 COM 对象.</p></dd>

  <dt>VarType</dt>
  <dd><p>表示值类型的整数. 类型列表见 <a href="ComObjType.htm#vt">ComObjType()</a>.</p></dd>

  <dt>Value</dt>
  <dd><p>要包装的值. 当前仅支持整数值和指针值.</p></dd>

  <dt>Flags</dt>
  <dd><p>影响此函数和包装器对象行为的标志, 请参阅后面.</p></dd>

  <dt>DispPtr</dt>
  <dd><p>原始的 IDispatch 指针.</p></dd>

</dl>

<h2 id="Flags">Flags</h2>
<table class="info">
  <tr>
    <td>&nbsp;0&nbsp;</td>
    <td>
      <p>默认行为. <a href="http://msdn.microsoft.com/en-us/library/ms691379.aspx">AddRef(增加引用)</a> 自动调用 IUnknown 和 IDispatch 的指针, 所以调用者应该适当使用 <a href="ObjAddRef.htm">ObjRelease</a> 释放指针的副本.</p>
      <p>未来版本中可能改变此默认行为, 因此建议当包装接口指针时总是设置<em>标志</em>为 <code>1</code>, 需要时再调用 <a href="ObjAddRef.htm">ObjAddRef()</a>.</p>
    </td>
  </tr>
  <tr>
    <td>&nbsp;1&nbsp;</td>
    <td>取得 IUnknown, IDispatch 或 SAFEARRAY(安全数组) 指针的所有权. 不调用 AddRef. 如果包装器对象包含 SAFEARRAY(VT_BYREF 除外), 那么当包装器对象被释放时会自动调用 <a href="https://msdn.microsoft.com/en-us/library/ms221702(v=vs.85).aspx">SafeArrayDestroy</a>.</td>
  </tr>
</table>

<h2 id="ByRef">ByRef <span class="ver">[v1.1.17+]</span></h2>
<p>如果包装器对象的<a href="ComObjType.htm"><em>变量类型</em></a>包含 VT_BYREF(0x4000) 标签, 可用空的方括号对 <code>[]</code> 来读写引用的值.</p>
<p>当创建一个引用, <em>值</em>须为变量的内存地址, 或足够存储指定类型的值的缓存. 例如, 下面的代码可以用来创建一个 VBScript 函数可以写入的变量:</p>
<pre>VarSetCapacity(var, 24, 0)
vref := ComObject(0x400C, &amp;var)  <em>; 0x400C 是 VT_BYREF 与 VT_VARIANT 组合而得.</em>

vref[] := "in value"
sc.Run("Example", vref)  <em>; sc 应像<a href="#ByRefEx">下面例子</a>一样进行初始化.</em>
MsgBox % vref[]</pre>

<h2 id="Remarks">一般说明</h2>
<p>当前版本中, 任何以"ComObj"开头的函数调用, 如果不匹配目录列表中的其他 COM 函数, 则实际调用 ComObjActive 函数. 如, <code>ComObjEnwrap(DispPtr)</code> 及 <code>ComObjActive(DispPtr)</code> 均等效于 <code>ComObject(DispPtr)</code>(隐式地, <em>变量类型</em>为 9). 此行为可能于后续版本不再可用, 故建议仅使用本页所展示的 <code>ComObject()</code> 及 <code>ComObjActive()</code>.</p>
<p>如果 ComObjActive 不能检索活动的对象, 则可能会抛出异常, 退出脚本或返回空字符串, 具体取决于当前的 <a href="ComObjError.htm">ComObjError</a> 设置和<a href="ComObjError.htm#factors">其他因素</a>.</p>
<p>当使用此函数包装或检索 IDispatch 或 IUnknown 接口指针时, 默认的行为会增加 COM 对象的引用计数. 因此, 当不使用时, 须<a href="ObjAddRef.htm">手动释放</a>接口指针. 当用于封装的对象被释放时, 他所包含的引用被自动释放.</p>
<p><b>已知限制:</b> 每次包装 COM 对象时, 都会创建新的包装器对象. 如 <code>if (obj1 == obj2)</code>, <code>array[obj1] := value</code> 这样的比较和赋值运算, 会把两个包装器对象视为独立的, 即使它们包含相同的 COM 对象.</p>

<h2 id="Related">相关</h2>
<p><a href="ComObjCreate.htm">ComObjCreate</a>, <a href="ComObjGet.htm">ComObjGet</a>, <a href="ComObjConnect.htm">ComObjConnect</a>, <a href="ComObjError.htm">ComObjError</a>, <a href="ComObjFlags.htm">ComObjFlags</a>, <a href="ObjAddRef.htm">ObjAddRef/ObjRelease</a>, <a href="ComObjQuery.htm">ComObjQuery</a>, <a href="http://msdn.microsoft.com/en-us/library/ms221467.aspx">GetActiveObject (MSDN)</a></p>

<h2>示例</h2>
<p>ComObjUnwrap(COM 对象拆包): 参见<a href="ComObjConnect.htm#Examples">ComObjConnect</a>.</p>
<pre class="NoIndent" id="ByRefEx">
<em>; 条件 - ScriptControl 需 32 位版本的 AutoHotkey.</em>
code =
(
Sub Example(Var)
    MsgBox Var
    Var = "out value!"
End Sub
)
sc := <a href="ComObjCreate.htm">ComObjCreate</a>("ScriptControl"), sc.Language := "VBScript", sc.AddCode(code)


<em>; 示例: 传递 VARIANT ByRef 至 COM 函数.</em>
var := ComVar()
var[] := "in value"
sc.Run("Example", var.ref)
MsgBox % var[]


<em>; ComVar: 创建可用于按引用(ByRef) 传值的对象.
;   ComVar[] 返回值.
;   ComVar[] := Val 设置值.
;   ComVar.ref 返回用于 COM 函数的按引用传值的对象.</em>
ComVar(Type=0xC)
{
    static <a href="../Objects.htm#Custom_Objects">base</a> := { __Get: "ComVarGet", __Set: "ComVarSet", __Delete: "ComVarDel" }
    <em>; 创建含 1 个 VARIANT 类型变量的数组.  此方法可以让内部代码处理
    ; 在 VARIANT 和 AutoHotkey 内部类型之间的所有转换.</em>
    arr := <a href="ComObjArray.htm">ComObjArray</a>(Type, 1)
    <em>;锁定数组并检索到 VARIANT 的指针.</em>
    DllCall("oleaut32\SafeArrayAccessData", "ptr", <a href="ComObjValue.htm">ComObjValue</a>(arr), "ptr*", arr_data)
    <em>;保存数组及可用于按引用传递 VARIANT 值的对象.</em>
    return { ref: ComObject(0x4000|Type, arr_data), _: arr, base: base }
}

ComVarGet(cv, <a href="../Functions.htm#Variadic">p*</a>) { <em>; 当脚本访问未知字段时调用.</em>
    if p.MaxIndex() = "" <em>; 没有名称/参数, 如, cv[]</em>
        return cv._[0]
}

ComVarSet(cv, v, p*) { <em>; 当脚本设置未知字段时调用.</em>
    if p.MaxIndex() = "" <em>; 没有名称/参数, 如, cv[]:=v</em>
        return cv._[0] := v
}

ComVarDel(cv) { <em>; 当对象被释放时调用.
    ; 必须进行这样的处理才能释放内部数组.</em>
    DllCall("oleaut32\SafeArrayUnaccessData", "ptr", ComObjValue(cv._))
}
</pre>

</body>
</html>